home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / ask11c.zip / ASK.DOC < prev    next >
Text File  |  1994-03-08  |  8KB  |  233 lines
  1.  
  2.  
  3.                                   ASK, v1.1
  4.                                 -------------
  5.                                 from TifaWARE
  6.  
  7.  
  8.  
  9.  
  10. What's New
  11. ----------
  12.  
  13.  
  14.      With version 1.1 I have significantly reorganized ASK's source code,
  15. placing commonly-used procedures, equates, and macros in separate files.
  16. Sharing code in this way will make it my programming task easier. From the
  17. user's point of view, however, the only change is that ASK no longer
  18. allows a space between '-t' and the time-out value. 
  19.  
  20.      Version 1.0 was the first public release of ASK.
  21.  
  22.  
  23.  
  24.  
  25. Introduction
  26. ------------
  27.  
  28.  
  29.      ASK is a simple utility for batch programming. With it you can ask
  30. questions in batch files and execute commands conditioned on the users'
  31. responses. And its ability to time-out makes ASK perfect for "hands-off"
  32. batch utilities.
  33.  
  34.  
  35.  
  36.  
  37. Usage
  38. -----
  39.  
  40.  
  41.      Running this program is a breeze. Assuming you've placed ASK.COM
  42. where DOS can find it, type "ASK -?" to display a brief help message
  43. similar to the following:
  44.  
  45.      TifaWARE ASK, v1.1a, 08/28/90 - ask questions in batch files.
  46.      Usage: ask [-options] [msgtxt]
  47.      
  48.      Options:
  49.        -l  = convert response to lower case
  50.        -tn = wait n seconds before timing out
  51.        -u  = convert response to upper case
  52.        -?  = display this help message
  53.      
  54.      msgtxt is an optional message to display.
  55.  
  56. [If you don't remember anything else, at least remember how to display
  57. this help message.]
  58.  
  59.      Typically you'll invoke ASK with some message text. ASK displays the
  60. text, then waits for the user to type a single character. After it detects
  61. a keypress, ASK exits with a return code equal to the ASCII character
  62. code; eg, 'Y' = 89, 'N' = 78, '<ENTER>' = 13, '1' = 49, etc... It's then
  63. up to you to check for specific values via the DOS ERRORLEVEL construct in
  64. a batch file.
  65.  
  66.      You can alter the actual value returned by using the '-l' or '-u'
  67. options. These set the return value based on the character's lowercase and
  68. uppercase ASCII character codes respectively. They are also mutually
  69. exclusive.
  70.  
  71.      You can instruct ASK to time-out rather than wait indefitely for
  72. input. Simply specify the number of seconds to wait using the '-t' option.
  73. If there's no input within that time ASK exits with a return code of 0.
  74. This lets ASK improve upon the DOS PAUSE command. That is, "ASK -t60
  75. Strike a key when ready . . ." duplicates PAUSE's functionality but waits
  76. for input only for a minute! 
  77.  
  78.      All of this may be somewhat confusing so here's an example. Let's say
  79. you sometimes, but not always, want to boot your machine with various
  80. memory-resident programs (aka TSRs). You can do this easily by adding the
  81. following to your AUTOEXEC.BAT file:
  82.  
  83.           rem Check whether to load TSRs
  84.           Ask -t60 -u Load memory-resident programs (Y/n)? 
  85.           if ERRORLEVEL 78 if not ERRORLEVEL 79 goto NoTSRs
  86.  
  87.           rem Load 'em
  88.           Print /d:PRN
  89.           Graphics
  90.  
  91.           :NoTSRs
  92.           rem Set environment variables
  93.           PATH=C:\BIN;C:\USR\BIN
  94.           prompt $p$g
  95.  
  96. Note how ASK is invoked here. ASK displays the text "Load memory-resident
  97. programs (Y/n)? " then waits for up to a minute for a response. It sets
  98. the return code to the uppercase equivalent of the user's response, if
  99. any. The next line just checks if ERRORLEVEL equals 78, the ASCII code for
  100. 'N'. Thus, if the user types either an 'N' or 'n' in this example, TSRs
  101. won't be loaded because execution branches to the label "NoTSRs". Any
  102. other response from the user causes TSRs to be loaded because execution
  103. falls through to the next statement.
  104.  
  105.  
  106.  
  107.  
  108. If You Have Any Trouble
  109. -----------------------
  110.  
  111.  
  112.      ASK will let you know of problems that arise. Here are the possible
  113. error messages and how you should deal with each:
  114.  
  115.      ask: illegal option -- x.
  116.           - Type "ASK -?" for a list of valid options.
  117.  
  118.      ask: time-out value not specified.
  119.           - When you use the '-t' option you must supply
  120.             a time-out value. This number represents the 
  121.             number of seconds to wait for character input
  122.             before aborting ASK.
  123.  
  124.      ask: time-out value too large -- 123456789.
  125.           - The time-out value must be between 0 and
  126.             43199 seconds (12 hours = 43200 seconds). 
  127.  
  128. These messages are written to the standard error device. In this way, they
  129. won't disappear down a pipe or into a file should you redirect ASK's
  130. output.
  131.  
  132.      Additionally, ASK uses a return code to convey information about the
  133. success or failure of its operation. Possible return values are:
  134.  
  135.      Code      Meaning
  136.      ----      -------
  137.      0         Time-out value reached without user input
  138.      1 - 254   ASCII code for character processed
  139.      255       Help message was displayed or time-out was too large
  140.  
  141. You can test for these codes using the ERRORLEVEL variable in a batch file.
  142. Refer to your DOS manual for a table of keys and their ASCII codes. 
  143.  
  144.  
  145.  
  146.  
  147. Limitations
  148. -----------
  149.  
  150.  
  151.      To remain portable across all computers running MS-DOS, ASK does not
  152. handle extended scan codes. What this means is that ASK distinguishes only
  153. alphanumeric and punctuation keys. Function keys or keypad keys lead to
  154. unpredictable results.
  155.  
  156.      Keys such as <SHIFT>, <CTRL>, or <ALT> do *not* count as keystrokes
  157. by themselves. They must be used in combination with others.
  158.  
  159.      To handle a time-out, ASK adds the value specified to the current
  160. time, then waits until the current time matches the result. Of course, the
  161. amount of time ASK waits for user input will be accurate only so long as
  162. the system clock does not change in some abnormal fashion. This might
  163. occur if you run ASK in a DESQview window and change the time in another,
  164. or if the system clock loses track of time around midnight while ASK is
  165. waiting for input. It's debatable whether this approach is "good".
  166.  
  167.  
  168.  
  169.  
  170. Requirements
  171. ------------
  172.  
  173.  
  174.      TifaWARE ASK runs on machines operating under DOS v2.xx or later, and
  175. requires about 2K of memory. It does not use BIOS calls, make direct
  176. writes to video RAM, or otherwise require machines to be "PC-compatible".
  177. In fact, ASK even runs properly on a DEC Rainbow!
  178.  
  179.  
  180.  
  181.  
  182. Who Owns It?
  183. ------------
  184.  
  185.  
  186.      I am releasing this program into the public domain. Since 1984 I have
  187. used public-domain software extensively, and I find it to be a terrific
  188. idea. Most programs are useful, and the source instructive. And they cost
  189. nothing! With this small contribution to the public domain I hope to pay
  190. back my gratitude to those other programmers who have made my computing so
  191. much easier.
  192.  
  193.      However, this program carries no obligation on my part to support
  194. users or provide future upgrades. I try to write clean code and believe it
  195. is "bug-free". Nevertheless, use this program ***AT YOUR OWN RISK***. Scan
  196. the source yourself, make any desired changes, and recompile the program,
  197. if possible. Make this standard practice with newly-acquired software and
  198. you'll not only protect your system from viruses but also get a better
  199. feel for exactly how programs work!
  200.  
  201.      As author of this program, I have two requests: First, please keep
  202. together the original source code, documentation, and executable if you
  203. distribute the package. This just makes it easier for others to use the
  204. software. Second, let me hear what you think of it - I'd appreciate a
  205. postcard with your comments. Enjoy!
  206.  
  207.  
  208.  
  209.  
  210. Kudos
  211. -----
  212.  
  213.  
  214.      Many thanks to Borland for its stand-alone debugger, which greatly
  215. reduced the time spent developing this program.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.                           George A. Theall
  223.  
  224.                              TifaWARE
  225.                          610 South 48th St
  226.                       Philadelphia, PA.  19143
  227.                               U.S.A.
  228.  
  229.                          george@tifaware.com
  230.                         theall@popmail.tju.edu
  231.                      theall@mcneil.sas.upenn.edu
  232.                      george.theall@satalink.com
  233.